Hello,
I’m working on my first document covering the setup and usage of a personal Development Environment. I was wondering if anyone could give me feedback that has experience dealing with technical documentation. This isn’t complete yet, but the body of it has a bit of information.
Thanks.
https://drive.google.com/open?id=1560YbslUfl04YsnNcnjv0pZbYlLAvXrH
I will do my best to take a look at this. What is the audience and skill level expected?
Thanks.
Junior System Administrators & Developers.
I’ll have an updated version shortly.
Excellent work. Is this your first time writing technical docs?
The only recommendation that I have is that you may want to add some check points at critical parts of no return. If you are not seeing X (or if you are receiving X after executing W), then you missed something, go back to step # . I see that you have a known issues section. Once you build that up, you may be able to just reference known issue # with some mitigation or explanation of the issue.
Also, thank you for not including sudo in everything. I really feel that that prevents people from just copying and pasting; forcing them to learn the commands and what they are actually doing.
Thanks! Yes it is.
Very good feedback!
Haha, you’re welcome. I just do everything for configuration as root because I like to keep history files clean and separate from day-to-day operations. I guess I could setup a separate user for that, but meh.
Here is the latest version:
https://drive.google.com/file/d/1kmoVzgFDjl5IT2wsLNXYuHcbUR5ekSxY/view?usp=sharing
Revision numbers start increasing once I have a base PDF that is “complete”. That should be when Jargon is done.
Very good job! Man, I would love to have such documentation in my job
Although I think that a lot of documentation looks weird in pdf form. I wonder if a keynote or something would be better to look at for text and code side by side.
Anyway:
Your documentation is better than 90% existing in the wild!
^ Tru.DAT