Where does Documentation fit In?

Replies to This Discussion

Permalink Reply by Rita Lewis on September 30, 2009 at 2:28pm

It is interesting you mention this problem because it falls into the heart of why corporations are slow to adopt Open Source solutions: its support is rather ad hoc and do it yourself. I feel comfortable because I follow the same practices as you and sometimes run into dead ends (if I don't want to pay some of the larger value-added prices for clubs or software).

I'm currently a tech support person at Dioscouri Design (they make JUGA, Ambra, SCRIBA, BILLETS, and other security and site management software). They work hard at building both the documentation as well as the tech support to be ultra responsive. The forum on the site has a strong community and is visited by the programmers. It is amazing (Rafael and Vika are part of this community and as the owner and senior manager of the company can speak more strongly on this) how much good will and sales develop through this attention to well-written and easy to access written and personal support.

I have to laugh and then cry at the documentation of extensions written by non-English speakers and I can just imagine how they feel about not having documentation in their languages. And then Programmers speak a whole nother language and I have problems when something says "add this code xxxxxx" and don't say where or how to customize it. Definitely writers are needed somewhere to professionalize this part of software development for Open Source and Joomla.

Permalink Reply by Peter van Westen (NoNumber) on September 30, 2009 at 3:39pm

I make extensions in my spare time and offer them for free.

So is there also someone that wants to write documentation for my extensions in their free time and offer it for free?

:D

Permalink Reply by Rita Lewis on September 30, 2009 at 3:43pm

good question. Maybe that is a list we could build here -- work that needs doing to help each other. I believe in barter. I would document if you could help me out with coding if I get stuck some day. I work a lot that way.

Permalink Reply by Mark W. Bender on September 30, 2009 at 4:30pm

That sounds like one of the great benefits of being a member of such a community as this one.

End Users will always benefit from well written documentation, and well written documentation will always benefit software. Software without well written documentation will create many problems for the End Users.

Sometimes I've got a great idea for some software, but at this point in time I don't know how to code to make the software. I can easily explain my concept/idea to a "coder", but am currently missing the coder. I'd happily help out with a software projects documentation in exchange for programming skills on a project that I'm working on.

Permalink Reply by Amy Stephen on September 30, 2009 at 7:36pm

I've seen a number of end users make the comment that JED should have better standards. All extensions should be documented for the install, usage, and removal. Support and forums must be available and language files. The project should verify the work, etc., etc., without considering that the reason developers can give work away freely is that there is no charge.

Permalink Reply by Amy Stephen on September 30, 2009 at 7:43pm

The best designed software is intuitive and requires no special handling. But, the vast majority of software doesn't reach that level. For commercial offerings, I can't imagine not providing excellent documentation. But, for free of charge software, it's a bonus if it's there. Well used software ends up getting documented. There's also a little niche market for writers. I think we have 4 or 5 Joomla! authors here. Kind of neat how that works out.

Permalink Reply by Rita Lewis on October 1, 2009 at 7:24am

It is interesting that you mention Joomla book authors because I've been watching this market closely. I'm a former book author and as publishing houses gobbled each other up, the opportunity to write introductory books dried up. Joomla! books seemed to have started in two arenas: self publishing such as what Barrie North did with his terrific Administrator's Guide and Plaqet (sp?), a small publishing house that is very admired in coding circles who began to publish terrific advanced Joomla! books. I tried to sell Sams a proposal for a Teach Yourself Joomla in 24 Hours but they didn't see a market. Now IDG/Dummies Guide has published Joomla! For Dummies you know Joomla! has become accepted into the mainstream computer book market. I think we'll see more specific titles from PeachPit Press, New Riders, Site Point, Wiley & Sons, and so on.

I agree that software should be intuitive, but a lot of software isn't because it is written by programmers who are thinking like programmers and not like users. Ars Technica had a terrific article about why so much corporate software is mediocre and it all has to do with not taking the time to study human interface design. Free software doesn't have to be as cryptic to use as some Joomla extensions are. Beautifully designed guis enhance usability and lead to many users. I know I gravitate to certain developers because their extensions are easy to install, work as promised, and do not require adding code to other files to function. Sourcerer happens to be a great example of such nice software. Install it and you can embed code into articles. It works and doesn't disobey Joomla! human interface guidelines (such as no way to get back to the extension's control panel or Joomla's control panel).

We need books to teach newbies how to understand a CMS and use Joomla, but more than that, we need programmers who are aware of how users use Joomla and write to their needs and Joomla standards. Then you wouldn't need documentation.

Permalink Reply by Mark W. Bender on October 5, 2009 at 10:23pm

All extensions should be documented for the install, usage, and removal. Support and forums must be available and language files.

Life would so much easier if the JED could manage to allow only supported extensions on it! Lack of support will kill a project very fast.

Permalink Reply by Mark W. Bender on October 5, 2009 at 10:29pm

For commercial offerings, I can't imagine not providing excellent documentation. But, for free of charge software, it's a bonus if it's there. Well used software ends up getting documented.

Commercial offering have the budget to pay someone to write the documentation. Open Source (Free) projects usually don't have a budget to pay someone to write the documentation, so it's usually up to the developer to write. Even if you have someone on your team writing your documentation, sometimes it's a matter of the persons doing the coding are moving at such a rapid pace that the software becomes a "moving target" for the documentation part of it.

Hopefully the articles for the sample data in the Joomla 1.6.0 releases will be updated with publication dates of 2009 or 2010 depending upon its release to the public!

Permalink Reply by Jeremy Wilken on October 6, 2009 at 5:29pm

Great point Mark, I have often wondered myself about the documentation and how it can be lacking. I admit my ignorance, but at the moment I don't know who is in charge of the Documentation Working Group or if it is that active. There seems to be some good pushes once in a while, and I find some good info on there that links to blank pages. So its a work in progress, always is for anybody, but I absolutely adore the CodeIgniter documentation. Of course, its backed by a commercial company, but its really a good model. See here http://codeigniter.com/user_guide/ for the information. Now Joomla is more complex than CI, but every function has a basic entry, and most classes have some example code. I don't think it dwells on the code very long, it provides short and to the point entries, and that is what I think Joomla can really benefit from. Yes, we have the API, yes we have the wiki, but the API provides autogenerated details that don't always help, and the wiki is missing things, because I think the pressure is to provide a lot of detail and information per page. Can we find other ways to just K.I.S.S. with the docs?

The whole avenue of video tutorials hasn't even been mentioned, but think about the power of that!

Permalink Reply by Amy Stephen on October 18, 2009 at 7:11pm

Mark - Would you please reopen this topic in the Learning Group, and then link back to this thread, if you want to continue this discussion? We are closing the home page forums for simplification. Thanks!