As most of you are aware the documentation for the framework is a little "patchy" (being kind) and needs to be updated.
Before I jump in and start churning out pages of useless, technically correct but practically worthless doco, I'd like your feedback on what you want to see.
Also a few questions
1. In general, where do you turn first for documentation? MSDN style docs (reference gudie), tutorials, wiki's, forums, google, etc?
2. How important are examples in the documentation? Are code snippets sufficient or do you need fully worked examples?
3. Do you need a getting started guide? Is the current guide usable or not worth the hard disk space it occupies?
4. Are you a "visual thinker". ie Do you need pictures in the documentation to help explain concepts?
5. Would you like the documentation to be able to be merged with the Visual Studio/MSDN docs?
6. What other ideas do you have?
Thanks for any feedback :-)
- Richard
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
1. In general, where do you turn first for documentation?
I usually hit google or MSDN. Solid HTML help in a standalone file would be good (if you've got the tools)
2. How important are examples in the documentation?
Code snippets are usually enough for me. But they are pretty important, esp from a development perspective.
3. Do you need a getting started guide?
Better than a getting started would be a single "example" that hits on all the major points. Heck, if you've got a testing framework, that would probably serve quite well as an example...
4. Are you a "visual thinker".
I don't need the pictures, but that's me. I find the "Reference" style format the best for API type stuff.
5. Would you like the documentation to be able to be merged with the Visual Studio/MSDN docs?
It'd be sweet if you were able to support merging and possible context sensitive help, not sure if that's possible, but yeah, it'd be very slick.
6. What other ideas do you have?
The obvious stuff I'd gloss over. I'm still unsure how some of the more arcane features are supposed to work (like caching, lazy loads, etc). So that's where I'd concentrate.
Just my 2c
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
As most of you are aware the documentation for the framework is a little "patchy" (being kind) and needs to be updated.
Before I jump in and start churning out pages of useless, technically correct but practically worthless doco, I'd like your feedback on what you want to see.
Also a few questions
1. In general, where do you turn first for documentation? MSDN style docs (reference gudie), tutorials, wiki's, forums, google, etc?
I tend to use all of the above, with preference to MSDN style docs and to developer forums.
2. How important are examples in the documentation? Are code snippets sufficient or do you need fully worked examples?
a) I think one commented, fully-worked example combined with a tutorial and a "how to get started" guide is a must. You already have a very good start with this three items; they just need polishing and fleshing out.
b) Snippets are a great way to show many problem/solution variations with a minimum of work. I think they're great. My feeling is that this is the greatest opportunity area for documentation improvement.
3. Do you need a getting started guide? Is the current guide usable or not worth the hard disk space it occupies?
Yes, a getting started guide is important. See #2a above.
4. Are you a "visual thinker". ie Do you need pictures in the documentation to help explain concepts?
Not important to me.
5. Would you like the documentation to be able to be merged with the Visual Studio/MSDN docs?
That would be nice if possible, but I have a more pressing need for the tools discussed in #2 above.
6. What other ideas do you have?
The documentation could be strengthened in the following areas:
a) An overview of the principle classes and interfaces used by the application developer. This is implied in some places, but hard to decipher.
b) Related to #a, more explanations for the various public interfaces of CPersistentObject, CPersistentCollection, CPersistenceBroker.
c) Deeper explanations of XML mapping options.
d) Peculiarities of mapping to various types of databases. (handling Nulls, etc)
For perspective on my comments, I'm still a newbie in using OOP and OR frameworks. I'm slooooowly getting on top of this stuff!
Thanks for any feedback :-)
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
1. In general, where do you turn first for documentation? MSDN style docs (reference gudie), tutorials, wiki's, forums, google, etc?
A: MSDN is one source of information. I prefer
to find this type of info directly on your own Atomic Frameworks site. All in one place.
2. How important are examples in the documentation? Are code snippets sufficient or do you need fully worked examples?
A: Not so much important. A broad picture helps me more.
3. Do you need a getting started guide? Is the current guide usable or not worth the hard disk space it occupies?
A: Yes, pls. And one that really helps guide as an entrance on how to install AF in eg. with VS2003 IDE. Also how to use in this IDE in comparison to ADO.NET.
4. Are you a "visual thinker". ie Do you need pictures in the documentation to help explain concepts?
A: No not particular, although I think it helps to confirm what I am doing as a developer myself in
e.g. VS 2003 IDE. And especially where I can go wrong.
5. Would you like the documentation to be able to be merged with the Visual Studio/MSDN docs?
A: Would be of much help. Yes.
6. What other ideas do you have?
None at the moment because I not even really started with AF. Although very anxious to use it.
Thanks for any feedback :-)
- Richard
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
Hi,
As most of you are aware the documentation for the framework is a little "patchy" (being kind) and needs to be updated.
Before I jump in and start churning out pages of useless, technically correct but practically worthless doco, I'd like your feedback on what you want to see.
Also a few questions
1. In general, where do you turn first for documentation? MSDN style docs (reference gudie), tutorials, wiki's, forums, google, etc?
2. How important are examples in the documentation? Are code snippets sufficient or do you need fully worked examples?
3. Do you need a getting started guide? Is the current guide usable or not worth the hard disk space it occupies?
4. Are you a "visual thinker". ie Do you need pictures in the documentation to help explain concepts?
5. Would you like the documentation to be able to be merged with the Visual Studio/MSDN docs?
6. What other ideas do you have?
Thanks for any feedback :-)
- Richard
I think that the documentation to be seemed a hibernate documentation.
1. In general, where do you turn first for documentation?
I usually hit google or MSDN. Solid HTML help in a standalone file would be good (if you've got the tools)
2. How important are examples in the documentation?
Code snippets are usually enough for me. But they are pretty important, esp from a development perspective.
3. Do you need a getting started guide?
Better than a getting started would be a single "example" that hits on all the major points. Heck, if you've got a testing framework, that would probably serve quite well as an example...
4. Are you a "visual thinker".
I don't need the pictures, but that's me. I find the "Reference" style format the best for API type stuff.
5. Would you like the documentation to be able to be merged with the Visual Studio/MSDN docs?
It'd be sweet if you were able to support merging and possible context sensitive help, not sure if that's possible, but yeah, it'd be very slick.
6. What other ideas do you have?
The obvious stuff I'd gloss over. I'm still unsure how some of the more arcane features are supposed to work (like caching, lazy loads, etc). So that's where I'd concentrate.
Just my 2c
Hi,
As most of you are aware the documentation for the framework is a little "patchy" (being kind) and needs to be updated.
Before I jump in and start churning out pages of useless, technically correct but practically worthless doco, I'd like your feedback on what you want to see.
Also a few questions
1. In general, where do you turn first for documentation? MSDN style docs (reference gudie), tutorials, wiki's, forums, google, etc?
I tend to use all of the above, with preference to MSDN style docs and to developer forums.
2. How important are examples in the documentation? Are code snippets sufficient or do you need fully worked examples?
a) I think one commented, fully-worked example combined with a tutorial and a "how to get started" guide is a must. You already have a very good start with this three items; they just need polishing and fleshing out.
b) Snippets are a great way to show many problem/solution variations with a minimum of work. I think they're great. My feeling is that this is the greatest opportunity area for documentation improvement.
3. Do you need a getting started guide? Is the current guide usable or not worth the hard disk space it occupies?
Yes, a getting started guide is important. See #2a above.
4. Are you a "visual thinker". ie Do you need pictures in the documentation to help explain concepts?
Not important to me.
5. Would you like the documentation to be able to be merged with the Visual Studio/MSDN docs?
That would be nice if possible, but I have a more pressing need for the tools discussed in #2 above.
6. What other ideas do you have?
The documentation could be strengthened in the following areas:
a) An overview of the principle classes and interfaces used by the application developer. This is implied in some places, but hard to decipher.
b) Related to #a, more explanations for the various public interfaces of CPersistentObject, CPersistentCollection, CPersistenceBroker.
c) Deeper explanations of XML mapping options.
d) Peculiarities of mapping to various types of databases. (handling Nulls, etc)
For perspective on my comments, I'm still a newbie in using OOP and OR frameworks. I'm slooooowly getting on top of this stuff!
Thanks for any feedback :-)
Also a few answers:
1. In general, where do you turn first for documentation? MSDN style docs (reference gudie), tutorials, wiki's, forums, google, etc?
A: MSDN is one source of information. I prefer
to find this type of info directly on your own Atomic Frameworks site. All in one place.
2. How important are examples in the documentation? Are code snippets sufficient or do you need fully worked examples?
A: Not so much important. A broad picture helps me more.
3. Do you need a getting started guide? Is the current guide usable or not worth the hard disk space it occupies?
A: Yes, pls. And one that really helps guide as an entrance on how to install AF in eg. with VS2003 IDE. Also how to use in this IDE in comparison to ADO.NET.
4. Are you a "visual thinker". ie Do you need pictures in the documentation to help explain concepts?
A: No not particular, although I think it helps to confirm what I am doing as a developer myself in
e.g. VS 2003 IDE. And especially where I can go wrong.
5. Would you like the documentation to be able to be merged with the Visual Studio/MSDN docs?
A: Would be of much help. Yes.
6. What other ideas do you have?
None at the moment because I not even really started with AF. Although very anxious to use it.
Thanks for any feedback :-)
- Richard
I've put an initial userguide (nowhere near complete) .chm file in the file releases for 2.2 RC1.
It contains details for the XML mappings, and a bit of other stuff.
Sorry it's taking a while to get done but it's slow work putting reasonable documentation together....