I have attached my report with suggestions of improvements and suggestions
for improving the
documentation.
- In the Installation Guide, the headings should have color to identify the
higherarchy like they do in the manual. Right now it is not easy to tell
which sections are parts of other ones because all of the headings look the
same.
- The commands in the Installation Guide should be shown like they are in the
manual so that it is easy to tell what parts are commands.
- "hello_svc.c" does not exist. The examples tell you to look at functions from
that file but all of the links to it just go to an error page.
- In section 1.1.6 of the manual, the command for compiling on Windows is too
long so you need to scroll over to see the end. This should be put on two
lines so that it is easy to read the entire thing.
- In section 2 of the manual, it should say near the folder names whether that
folder is mandatory or optional so that it is easy to find that information
quickly.
- Both the "Module Folders" and the "Service Folders" sections of the manual
say that they are section 2.1.
- In section 3 of the manual, axis2_create_instance and axis2_remove_instance
should be in the table with the other functions.
- The methods in section 4 should be put into a table like the ones in section
3 to make it uniform.
- The functions in section 9 should be organized into a table like they are in
section 3 so that it is all the same.
- In the section 13 ("Using SSL Client") the "NOTE:" parts should be the same
gray color that it is in all of the other sections.
- The subsections in sections 1 and 2 have their own numbers (1.1.1, 1.1.2,
etc.). The numbering for subsections stops after section 2. The rest of the
subsections should have numbers too so that it is easier to tell what part
it is.
- The newlines after code examples should be removed so that it looks nicer
and it takes up less space.
- The appendices should each be named instead of just being labeled "Appendix
A", "Appendix B", etc.
- It would be nice to have another section of the docs that went over the
samples
that are provided and how they work. This would show how to take what is
learned
in the manual and apply it do different situations.
Conclusion
The current documentation for the Axis2/C project is good but should be more
uniform than it is now. A lot of things are done in different ways throughout
the docs and should be changed to make it seem more consistent. In sections that
describe functions and methods, the functions and their descriptions should be
put into a table like they are in section 3. It would be much easier to navigate
if each subsection had a number like they do in the beginning of the manual. The
actual content of the documentation is great but it needs some work on
organization
and consistency.---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
