GitBuilding a new documentation tool?


#1

I know a lot of us are passionate about documentation (as shown by the active debate in GOSH 2018) but we tend to find it hard to make good documents. @rbowman and I have spent a lot of time agonising over how documentation should be done. The crux of the matter seems to be an argument over “the perfect system” vs. “something we can implement quite easily”.

I have started to build something which falls into the “something we can implement quite easily” category. The idea in it simplest form is: Humans are good and descriptions, and computers are good at counting. With this as a starting point we took a format people are comfortable with: markdown (Posts on this forum are written in markdown!), and have extended it to add meta data about parts so they can be counted.

I called the software Git Building as I like puns. You can find it on GitLab and as of today anyone with Python 3.6 or higher can install it with the command:

pip install gitbuilding

I hope to have more a more friendly install process in the future.

I have provided a little FAQ below.

Should I use it?

Yes, but also no. The software is in early stages and is likely to change quite a bit, so I wouldn’t put all your work in it right now unless you are willing to keep updating it as we learn. That being said, we only learn from feedback. The more people that try to document something simple, get problems and shout at me, the better it will be. Please either shout here or on the issues on GitLab, about any errors and anything that annoys you.

How do I use it?

There is documentation on the syntax.

For now the software is command line only (this will change too!!). Once installed navigate your terminal/command prompt to an empty directory and run:

gitbuilding new

This should create you a new example documentation. Next you can build it with:

gitbuilding build

Finally run:

gitbuilding serve

This should give you a message saying it started a server at http://localhost:6178/. Open this link an a browser and you should see some documentation which looks a bit like this:

Is there example documentation

Yes there is and it has cheese and pickled eggs! You can see it poorly rendered here. This will improve soon when we can export HTML, for now it is best to download and run:

gitbuilding build

then

gitbuilding serve`

You said to give feedback, should I complain about every detail?

Yes! If it is slightly annoying people won’t use it. Please shout about everything. If it crashes because you made a simple typo, please give me a specific example and I try to make it behave more gracefully. If you got confused installing it, tell me, I will try to improve the instructions. If you just don’t like it, that is still useful feedback. If you love it, that is cool too!

Why is it called Git Building? Does it use git?

This is a good point and it might be a bad name (but I like it). The reasoning goes something like this: We could do with a simple standard way to type documentation, a type of markdown. For this we need to agree a standard, and we need to implement it. The standard should set out how to define parts, and categories, how to count them and arrange documents. The implementation is something that turns that into reality.

Git Building is an implementation. The standard itself should have a different name (@kaspar has suggested Markdown Buildup which is fantastic!). I see the Git Building as doing more than rendering the standard, I want it (eventually) to have a nice GUI for those who don’t like command line. I want it to export nice documents to for web viewing (it sort of does that), I want it to render your CAD models (I think I know how to do this for STLs), and I want it to interface with repositories like GitLab to provide a nice interface for those wishing to do hardware that are not software people. But we must walk before we can run. What I have now is baby software taking its first steps. Please criticise my baby!


#2

Hi @julianstirling I love this idea. I am working on similar stuff as well.

  • This is a tool I made to make BOMs with yaml. It works but is still an idea.
  • I like the concept of bundling files to make a BOM as you are proposing.
  • For documentation I am also using vuepress based templates, they can also be automated. The good thing to keep in mind is to design for local/online integration. Markdown is a great choice.

This is one example of the templates I have been using to document our projects:


#3

Hi Jose,

Thanks! I LOVE the built in editor for BOMAKE :heart_eyes:

I notice that BOMAKE is “No license. All rights reserved”. I would really like to see if I can integrate some of the editor into GitBuilding, for this I would need your permission to relicense parts of the code under GPL. Also if you want to get involved with GitBuilding that would be wonderful, either doing testing or writing code?

As this projects progresses we hope to standardise the file format more formally. As part of this we will probably get some impartial people with experience writing standards to contact stakeholders so that we end up with a format that is good for everyone, not a format that is good for just me. If/when we reach this stage are you happy for me to put them in contact with you, as you have clearly spent time thinking about the same problem.


#4

Hi Julian, Thanks :smile:
Should be Licensed properly, I focused on building in t his phase. I am really opened for suggestions here. Just point to a license that you think is good.
About the gitbuilding, I have been worlking on something similar with vuepress based templates.
Maybe we should just meet and talk more about the work we are doing, is good to join forces :slight_smile: