Recommendation when we need to omit sections from user guide / developer guide?

[btzy]

My user guide and developer guide is way too long to fit into the ten pages allowed for the project portfolio page, because the feature has many sections. What would be the best way to omit content so that it will fit within the ten-page limit?

I think this might also depend on whether CS2103 will be grading us directly from the UG/DG or using the PPP only.

Option 1 : Cut out whole sections from the project portfolio page.
Pros: This will allow the remaining sections to retain the most readability, so I can demonstrate documentation skills.
Cons: If CS2103 is going to use the PPP for grading, some parts of my feature would be totally gone.

Option 2 : Cut out small parts of each section, but make sure to retain all sections at least in some form and retain all diagrams.
Pros: If CS2103 is going to use the PPP for grading, all features will be present in some manner.
Cons: Much elaboration and clarification about each section will be gone, so it would be much harder to understand the design choices taken.

CS2101 suggests taking option 1, because it retains most readability, which is good when employers read it. In fact, our CS2101 lecturers seems to think that CS2103 directly reads the UG and DG, instead of the PPP when grading our project contributions. The CS2103 website seems to suggest otherwise (i.e. we will be graded on our project contributions and documentation writing based on the PPP). Which is correct?

If CS2103 will grade us on project contributions and documentation writing based on the PPP (instead of the UG/DG), then it seems that I should choose option 2, and ensure that all my diagrams and visuals are included in the PPP. Am I correct to say that CS2103 will grade us on project contributions and documentation writing based on the PPP instead of the UG/DG, and hence I should choose option 2?

[damithc]

You can give a representative sample(s) of UG and DG that showcases your documentation skills and still understandable on its own. For the parts left-out, you can give an abbreviated version and refer the reader to the full UG/DG for more details.
e.g.,

Heres' how feature X works for situation Y.
{Extract of UG}
Feature X can also be used for situation A, B, C, the details of which can be found in the User Guide.

[btzy]

@damithc Thanks Prof for the quick reply!

So... CS2103 will still look at our real user guide / developer guide when grading us for implementation and documentation? (E.g. some UML diagrams that are not present in the PPP but are in the DG)

[damithc]

So... CS2103 will still look at our real user guide / developer guide when grading us for implementation and documentation? (E.g. some UML diagrams that are not present in the PPP but are in the DG)

Keep in mind that these submissions are peer-graded (in the PE) which needs to be done in a limited time span. Hence the need to limit the length.

It's similar to giving extra details as appendices; the reader will look at the UG/DG if the PPP is not enough to make a judgment. For example, when judging documentation quality, if the part in the PPP is not well-written, there is no point reading the rest in the main UG/DG. That's why you need to put the most representative part of your writings in the PPP and still give an abbreviated version of the rest in the PPP itself. Even when judging the quantity of work, the reader should be able to get a good sense of the quantity by combining what is quoted in the PPP and your abbreviated description of the missing part. There is no guarantee that the evaluator will read the full document.

[btzy]

Thanks Prof, I guess I'll put a least a mention of every section inside the PPP then!