[unicorn] Short Review of Unicorn Project Documentation

Hi Damien, Jean-Gui,

This is a simple review of the documentation about Unicorn Project.  
There is room for improvements, not necessary, today and right away  
but definitely on the middle term.

The document seems to be a requirement document. Though I would  
encourage to push forward by making it a Developer Guide. Here is a  
suggestion for an outline, you can propose better things and ideas.

1. Simple Introduction about the project
   Concrete use case as an example (short)
2. Global Architecture of Unicorn
     2.1 Unicorn Architecture
     2.2 What is WADL?
3. Technical Description of the Code and Features
4. Howtos
     4.1 How to develop a module for Unicorn
     4.2 How to develop a Web service that can work with Unicorn
     4.3 How to help for localization
     4.4 How to install the service on your own network
5. Appendixes
     Bug Reports, Contribute to the code, etc.


Here is another example of documentation about Web Services
http://developer.apple.com/documentation/Networking/Conceptual/ 
UsingWebservices/
http://developer.apple.com/documentation/Networking/Conceptual/ 
UsingWebservices/Web_Services.pdf

Graphics:
If you need graphics to illustrate a concept, please ask me. I will  
discuss with you about the best way to communicate what you want to  
illustrate and I will create them.


Editorial:
* s/Book of Specifications/Unicorn Developer Guide/

* "About this document" section: remove it. Make a note about who's  
in charge etc. But the information up front is not necessary  
interesting for the developers who are coming back again and again.

* Remove everything which is related to the internship in particular.  
Focus the discussion around Unicorn. Unicorn is the topic, not the  
document, nor the internship.
For example, a sentence like
	"The aim of our internship is to create a
	"universal validator" that will be able to
	validate and check multiple things in a
	document through a single Web interface."
could be rewritten as
	Unicorn is an observer framework to gather
	the conformance and validation tool results
	for a Web resource through a single Web
	interface.

For your valuable contribution and creation of the project, create an  
appendix keeping the history of the project, where you can talk about  
the internship, etc. We will then be able to add other contributors  
and how it has evolved.


* First person: Remove everywhere in the document the first person,  
things like "In the following I will often use the term UniCORN"  
could be rewritten like
	"The central module of this tool is called UniCORN"


Each time, you are rewriting a section, think about this:

	- What concepts do I want to explain?
	- Could I imagine a graph, drawing for what I'm explaining?
	- Could I write it in a simpler way?
	- Can I give an example? (code, use case)
	- Will a screenshot help to understand? (for example UI)
	- When describing code features
		Can I write a synthetic list of the feature.
		Give a link to the hard core documentation


When you rewrite a section, give it to read to a developer who has  
*zero* knowledge of the project. Do not try to contradict his/her  
questions or comments (even the person says that the document is  
really written by donkeys ;) ).
	- Write down the questions
	- Give answers, when possible
	- Improve the document to make it clearer


Do not try to rewrite everything in one shot. Once you have agreed on  
an outline for the document, pick up one section, give you 2 hours to  
write it and 30 minutes to read it, and write down a list of issues  
you have seen on your own writing. Let it rest for a while. Do that  
at least once or twice a week.

After a few weeks/months, the document will be good. ;)

-- 
Karl Dubost - http://www.w3.org/People/karl/
W3C Conformance Manager, QA Activity Lead
   QA Weblog - http://www.w3.org/QA/
      *** Be Strict To Be Cool ***

Received on Thursday, 7 September 2006 06:54:11 UTC