Repository navigation
overall website structure and type of content has room for improval #117
Description
this is an anchor issue about the overall website structure - what I am thinking about is:
- how do we best encourage users to contribute?
- which types of contents would we like to add - and make easy to add while at it?
- examples: application reports, reference material, a bibliography, videos ("CNC p0rn") a 'news column', status updates, a tag cloud?
- should we integrate the blog into the website? (I think yes, and it should become open for all users to blog there; I also think it should generalize focus from BB issues)
- toplevel categories: do they make sense?
- does the navigation means make sense? how do we improve it (eg deeper structured topic bars on the right hand side)
This issue is more general in scope than #103 - which focuses on the documentation proper (manuals, man pages) - therefore documentation-specific themes should go to #103
Activity
ArcEye commentedon May 31, 2016
A BIG problem with contributions, is that most of the easily accessible information is in the
index-???? docs
Because they just include other docs, if a user spots a mistake and tries to 'Edit this page' , all they get is a list of links, not the content they wanted to correct.
It is possible to navigate to the document you want and do the edit, but will they?
luminize commentedon May 31, 2016
Could we make an “edit-this-section” button nest to the applicable header???
ArcEye commentedon May 31, 2016
I don't think so, the github layout and the index layout differ at a basic level
eg
From http://www.machinekit.io/docs/index-HAL/
click on
Basic Hal tutorialThe underlyiing URL has some relationship to the github structure
http://www.machinekit.io/docs/index-HAL/#basic-hal-tutorial
ie
if you inserted
hal/ in place of '#'However if from the same page you click on
HAL Commmandsyou gethttp://www.machinekit.io/docs/index-HAL/#sec:Hal-Commands
This URL does not even mention the document which originally contains the section
so conversion becomes very difficult.
As far as I am concerned, this include:: link has caused us nothing but problems from the outset and we should seriously consider replacing it with conventional index documents.
Then it will always show the URL of the document you are actually in, not an included link which physically lives somewhere else.
luminize commentedon May 31, 2016
So if we would remove that anchor in that header, then I’m 99% positive that the link/anchor would become http://www.machinekit.io/docs/index-HAL/#hal-commands
But we should still use include links when we have re-usalbe info, like in getting started instructions. http://www.machinekit.io/docs/index-getting-started/#setting-up-machinekit-on-a-platform http://www.machinekit.io/docs/index-getting-started/#setting-up-machinekit-on-a-platform
Also a multitude of index documents with links will make navigating horrible and hard to maintain.
mhaberler commentedon May 31, 2016
I agree to disagree ;)
this is why include in asciidoc is wrong in this website, and unfixably so:
include breaks the relation between the edit-this-page link (including file) and the content rendered (included file).
This is it. Include has to go, there is no way around it, toc or not.
NO - it is NOT going to work. Period.
Sorry to bang on the table: the underlying problem seems not to have come across: the filename used for edit-me and where the content is coming from must match no matter what. And include breaks that . No exceptions, no kludges, no tocs, no workarounds will ever fix that.
And for that particular task, we must find another means - the repetition in the output is mindnumbing. The tunnel page approach was so-so, and the repetition still is.
We will find a way without include.
Include has to go. That is item Nr 1 in the yet-to-be-written style guide.
mhaberler commentedon May 31, 2016
Blog integration - in case we want to insource Charles' site into this site, there is a tool to do the one-off import: http://import.jekyllrb.com/
Exporting from blogger.com is easy - single huge xml file.
Something to play with on a local jekyll install first, and explore if the workflow of new blogposts is for humans.
mhaberler commentedon May 31, 2016
On @ArcEye 's question about videos:
We currently have a directory/link based organisation. This is not particularly flexible in arrangement and navigation.
I think tagging content could be a tool to solve this organisation problem. Play with jekyll collections to see how that can be done.
Our categories ("Installation reports" "reference material", "videos", but also the "news column", "status updates" would just be tags which go into front matter (several possible). The rendering step than can arrange the posts for the different locations: news column is a scrollup on the landing page, Installation reports would become a proper docs section.
Another item to play with offline first. @sliptonic - what do you think about this?
ArcEye commentedon May 31, 2016
I actually don't see any problem with having a link which goes to an 'external' site, if blog.machinekit.io can actually be regarded as such.
It was raised as a 'problem' in the initial rash of comments to sliptronics missive, but I failed to see the problem then and still do.
Right click and 'Open in new tab' or use the Back arrow when finished - sorted.
If it isn't broken...............
ArcEye commentedon May 31, 2016
The other thing against the need to incorporate blogs into the documentation 'engine' we have developed, is that they don't change.
By their nature blogs are throw away 'dear diary' pages.
If something new comes up, you don't edit the previous blog, you write a new one.
mhaberler commentedon May 31, 2016
@ArcEye fair enough on the blog, enough frontlines open right now.
@cdsteinkuehler - how do you think about:
ArcEye commentedon May 31, 2016
If you want to retain editorial control, blogs can be input to the SandBox and you can be sent them for inclusion (in whole or part) or not, at your discretion.
cdsteinkuehler commentedon May 31, 2016
On 5/31/2016 10:09 AM, Michael Haberler wrote:
I would TOTALLY love this. I've wanted more people to craft blog
articles, it just hasn't seemed to happen.
The blog is focused on the BeagleBone and FPGA development, since
that's what I've been working on (so what I make posts about). More
contributors will hopefully help to broaden the content topics.
One question is what to do about some of the static blog pages. I
don't think the blog is currently the best place for the BBB capes
hardware page, or the Machinekit image instructions, but some sort of
placeholder should probably stay and redirect folks to the correct
spot in the official docs. Other pages (like my BeBoPr bridge
instructions) can be moth-balled or maybe just axed.
Maybe there should be x86 and SoC+FPGA hardware pages as well?
Charles Steinkuehler
charles@steinkuehler.net
ArcEye commentedon May 31, 2016
preview.machinekit.io has a demo HAL index page with all direct links
EDIT:
Or it did, overtaken by the next PR
Anything therein that is rendered through 'Edit this page' then produces the correct github page.
I don't see the problem with doing all indexes this way, not quite as pretty, but I am sure that can be addressed, the main thing is editing works the way the user will expect.
luminize commentedon May 31, 2016
Sorry, but the problem has come across. I fully understand that the filename and content must match. I think you miss my worry about reusing content.
I’m convinced that we need to keep the user/reader into the picture. This entire action has been about lowering the barrier to contribute and to read. Let’s keep the reading in mind for first time users.
A new user that wants to start with Machinekit should have to:
With that in mind, plus the phletora of choices on current and future platforms (arm, x86, x86_64, arm64?, fpga?) and distro’s (jessy, wheezy, and future? centos? fedora?) will exponentially increase the choices. We’ll have a beast (no, correction: a zoo) to maintain if we don’t find a way to re-use parts of text. Think how we would program. We re-use code. And we should be able to re-use text.
And that makes me say:
Until we have a better solution, let’s not get fanatical and accept ::include in certain situations, where we can expect that the level needed to edit is a little bit higher.
ArcEye commentedon Jun 1, 2016
I had great difficulty understanding what you were talking about, but I think I do now.
The use of toc: produced a sub-menu, which actually shows you what is in each document and allows you to navigate to that section directly.
The downside however is that the entire manual is rendered as a single page and the edit link does not work.
I have a compromise in mind, I will demo it later when done.
Just a question of whether it has to be manual or if I can find an automatically rendered solution
ArcEye commentedon Jun 1, 2016
Just done PR #150
Look at it before it gets overwritten, hopefully best of both worlds
ArcEye commentedon Jun 1, 2016
See PR #151
4 of the 6 indexes overhauled