Board index FlightGear Development Documentation

Technical writing (split from Command line arguments with...)

Discussion of the FlightGear documentation, how it can be improved and coordination of people working on it.

Technical writing (split from Command line arguments with...)

Postby Johan G » Sat Mar 21, 2015 9:10 pm

Sorry, a bit of topic as technical documentation is a pet peeve of mine. :roll:

wkitty42 wrote in Sat Mar 07, 2015 8:35 pm:for me, it isn't that they are pathetic... it is that some information is left out... in one of my other lives, i'm a member of a technical documentation team... others on that team just do not understand the need of using plain layman's terms and explaining the most basic of concepts... they don't understand this because they assume that only developers are going to be interested in the documents... what they forget is that the laymen users of the technology want to learn how it works to they try to read those same docs and they end up in the same position as the OP, myself and others who are trying to understand and are at least asking questions instead of giving up because it is too hard to understand...

One of the principles to consider when writing technical documentation is to 'write out the obvious'. When writing technical documentation you at least have spent a lot of time on trial and error, reading in on a subject and/or developing a feature yourself. What is too obvious to write for someone can be the missing piece in the puzzle for someone else. It is surprising how often that have been the case when I am trying to learn something in FlightGear (and other contexts as well).

In addition to that there is of course all those other things one can do as an article writer to help the readers cognitive processes, for example:

  • Beginning with a brief overview*
  • Briefly explain terms on their first occurrence in an article
  • Having a good section and subsection structure
  • Not repeating oneself or having too many similar visual cues
  • Possibly ending with a conclusion
  • Referring to related content (for example articles and/or categories)
* This is also very helpful in letting the reader know he is reading the wrong article before he has already read half of it. Been there, done that. Too many times. :wink:
Low-level flying — It's all fun and games till someone looses an engine. (Paraphrased from a YouTube video)
Improving the Dassault Mirage F1 (Wiki, Forum, GitLab. Work in slow progress)
Johan G
Moderator
 
Posts: 5292
Joined: Fri Aug 06, 2010 5:33 pm
Location: Sweden
Callsign: SE-JG
IRC name: Johan_G
Version: 3.0.0
OS: Windows 7, 32 bit

Re: Command line arguments with 3.4 launcher?

Postby clrCoda » Sun Mar 22, 2015 3:51 pm

There are tons of technical writting howTo's and help guides in PDF form and in websites on the net.

Here's just the pdfs google put first

https://www.google.com/search?q=technical+writing+pdf&rlz=1C1DVZA_enUS347US355&oq=technical+writing+pdf&aqs=chrome..69i57.8870j0j1&sourceid=chrome&ie=UTF-8
Ray St. Marie
clrCoda
 
Posts: 1228
Joined: Wed Apr 07, 2010 11:04 am

Re: Command line arguments with 3.4 launcher?

Postby Hooray » Sun Mar 22, 2015 4:08 pm

No need to post random links ...

I think there are several contributors who obviously do have a background in technical writing - as usual, it is a matter of spare time and different priorities.
I have seen end-users with zero coding background apply those docs within a few weeks of playing with the docs and examples there.
So I guess it's also a matter of different mentalities and expectations.
Personally, I don't see any merits in discussing this on the forum if this is about certain articles in particular - I would much rather see that the exact same people disagreeing with the nature of those articles, get/create a wiki account and provide feedback right on the corresponding article's talk page - IMO, that is indeed what it's there for. And once forum users have a wiki account, there's no barrier to entry anymore to help and get involved in contributing/improving the wiki. And please don't worry about technical writing at all - we do have tons of articles containing poor grammar, or even just typos or colloquial language - all of which could be easily fixed by people, even without having to understand any FlightGear specific technologies at all.
Equally, many articles are lacking formatting or even just a few drawings and/or screen shots to visualize important concepts.

I am not saying that those articles cannot be improved - they certainly can be improved, and I am not in the best position to judge their quality, because I am responsible for most of those, while also being familiar with the corresponding concepts - however, if people are genuinely interested in seeing our docs improve over time, please be as specific as you can be, and use the wiki itself to discuss such articles - and please show some engagement/involvement, too - good feedback would allow any of us to review and improve those articles within 20-30 minutes.

But the kind of discussion we're currently having here is unlikely to yield any tangible results at all.

PS: Most of us hold at least 1-2 degrees in CS/SE, which usually also involved technical writing at some point - so we're quite likely to be familiar with the requirements, which is why posting PDFs or "best practices" is kinda moot - just like the quality of the source code in SG/FG and FGData is a compromise between spare time and expertise/skills, it also is a testimony to the huge area of domains that need to be covered by a flight simulator like FG (maths, physics, visualization, 3D rendering, computers, algorithms, data structures etc), as well as a base of contributors that is not particularly sizable, but which still is in flux and varies hugely over time. All of this is also applies to the quality of the documentation just as well - it just might be a bit more visible. But then again, the wiki is primarily a resource maintained by the community, with only very few core developers even being regular wiki contributors at all, and even fewer bothering to provide technical documentation, or even just end-user documentation, which applies even just to $FG_ROOT/Docs and the README files there (think recently modified/added fgcommands)
Please don't send support requests by PM, instead post your questions on the forum so that all users can contribute and benefit
Thanks & all the best,
Hooray
Help write next month's newsletter !
pui2canvas | MapStructure | Canvas Development | Programming resources
Hooray
 
Posts: 11163
Joined: Tue Mar 25, 2008 8:40 am

Re: Command line arguments with 3.4 launcher?

Postby clrCoda » Sun Mar 22, 2015 7:06 pm

Sorry, Hooray, if my post was somehow interpreted by you as some form of slight. Not in the least. The thread had taken a turn towards a topic I have a slight interest in, and when I looked up the pdfs available, hoping to find an old favorite from many years ago, I was delighted to find the field of pdfs on this subject filling in nicely.
Nothing I ever say is meant to be interpreted as a personal slight, tho I'm often correctly shown by others how insensitive some of the things I type/say are.

My bad. :)
Ray St. Marie
clrCoda
 
Posts: 1228
Joined: Wed Apr 07, 2010 11:04 am

Re: Command line arguments with 3.4 launcher?

Postby Hooray » Sun Mar 22, 2015 7:20 pm

I still do think that you could/should get involved in the wiki and provide and feedback there - and if it's too generic to be applicable to one particular article (as per Johan G's posting), you could still help and come up with a "howto" (list of guidelines) on technical writing, to help others get started contributing such articles to the wiki
Please don't send support requests by PM, instead post your questions on the forum so that all users can contribute and benefit
Thanks & all the best,
Hooray
Help write next month's newsletter !
pui2canvas | MapStructure | Canvas Development | Programming resources
Hooray
 
Posts: 11163
Joined: Tue Mar 25, 2008 8:40 am


Return to Documentation

Who is online

Users browsing this forum: No registered users and 1 guest

cron