Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
overall website structure and type of content has room for improval #117
this is an anchor issue about the overall website structure - what I am thinking about is:
referenced this issue
May 30, 2016
A BIG problem with contributions, is that most of the easily accessible information is in the
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?
Could we make an “edit-this-section” button nest to the applicable header???
I don't think so, the github layout and the index layout differ at a basic level
The underlyiing URL has some relationship to the github structure
However if from the same page you click on
This URL does not even mention the document which originally contains the section
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.
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.
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.
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.
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?
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.
If it isn't broken...............
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.
On 5/31/2016 10:09 AM, Michael Haberler wrote:
I would TOTALLY love this. I've wanted more people to craft blog
The blog is focused on the BeagleBone and FPGA development, since
One question is what to do about some of the static blog pages. I
Maybe there should be x86 and SoC+FPGA hardware pages as well?
referenced this issue
May 31, 2016
preview.machinekit.io has a demo HAL index page with all direct links
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.
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.
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.