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!
