overall website structure and type of content has room for improval

[mhaberler]

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

[ArcEye]

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]

On 31 May 2016, at 13:05, ArcEye [email protected] wrote:

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?

I think they get lost. If you want to change a part of HAL manual, which is ::include in an ::include you have exactly 99% chance to not find the section you want to change.

Could we make an “edit-this-section” button nest to the applicable header???

[ArcEye]

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
eg
From http://www.machinekit.io/docs/index-HAL/
click on Basic Hal tutorial

The 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 Commmands you get
http://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]

On 31 May 2016, at 14:03, ArcEye [email protected] wrote:

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
eg
From http://www.machinekit.io/docs/index-HAL/ http://www.machinekit.io/docs/index-HAL/
click on `Basic Hal tutorial

The underlyiing URL has some relationship to the github structure
http://www.machinekit.io/docs/index-HAL/#basic-hal-tutorial 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 Commmands you get
http://www.machinekit.io/docs/index-HAL/#sec:Hal-Commands http://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.

This is probably because I have inserted a :toc: which generates these anchors because they are headers inside the index-HAL document (index-HAL then has become one big huge document), and sec:Hal-Commands (because it is manual added anchor, in the document that has been included) overrides that ???

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

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.

I don’t fully agree, It's a question of what you use it for. The docs need to be hacked into pieces which better fit together. Not these humongous manuals. So more smaller documents, less include links should be the goal.

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]

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.

But we should still use include links when we have re-usalbe info, like in getting started instructions.

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]

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]

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]

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/

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]

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]

@ArcEye fair enough on the blog, enough frontlines open right now.

@cdsteinkuehler - how do you think about:

• opening the blog for users at large
• thematic: steering away a bit from the Beaglebone scent towards a general Machinekit community blog?

[ArcEye]

@cdsteinkuehler - how do you think about:
opening the blog for users at large

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]

On 5/31/2016 10:09 AM, Michael Haberler wrote:

@cdsteinkuehler https://github.com/cdsteinkuehler - how do you think about:

• opening the blog for users at large

I would TOTALLY love this. I've wanted more people to craft blog
articles, it just hasn't seemed to happen.

• thematic: steering away a bit from the Beaglebone scent towards a general
  Machinekit community blog?

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
[email protected]

[ArcEye]

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]

On 31 May 2016, at 16:05, Michael Haberler [email protected] wrote:

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.

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.

We will find a way without include.

well, I truly hope we find a simple one.

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:

• choose his/her setup
• have 1 page with all the instructions in front of their nose, and stay on that page during the setup. That means no clicking thru a hansel und gretl breadcrumb-follow-this-trail-and-loose-the-way instruction (because the birds ate the trail).

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]

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]

Just done PR #150

Look at it before it gets overwritten, hopefully best of both worlds

[ArcEye]

See PR #151

4 of the 6 indexes overhauled