I saw some questions raised about the folder structure of source codes, but I never see the question about folder structure of project documentation. I googled it and still do not see many articles talk about.
Here is one http://www.projectperfect.com.au/downloads/Info/info_project_folder_structure.pdf
To quote some of its words:
"There are two broad approaches:
Organize by phase so that each top
directory is a phase. For example,
you might have directories for
Feasibility, Business Analysis,
Design etc. or whatever your phases
are called.
Organize by function so that the top
directory level are functions. For
example, Risks, Requirements, Scope,
Change Control, Development.
Most times a mix of both are used..."
So any thought about it? I believe this is also an important issue!
IMHO depending on your document management system the choice of structure for your documents may not be an issue. When looking at the problems project related documents are trying to solve you typically come to the conclusion that documents are about communication.
Different documents attempt to communicate different things (or contexts); test plans discuss how testing should/has been executed, requirements specifications discuss how the business rules should be applied, architecture documents discuss the technical components and so forth. Each of these documents might have the need for its own unique structure. For example the structure you choose for your test plans may be vastly different from the structure you need for your architecture documents.
When keeping the communication issue and the document context in mind I generally come back to these 2 key aspects.
Searchability – What is the easiest way to find the document I am looking for?
Versioning – How do I know that the document I am looking for is the most recent one?
I feel searchability is the most important thing to remember because different people call the same document by different names. For example some people call Business Requirements documents Functional Specifications. Some people call Functional Specifications use case documents. As you cannot always govern the naming convention of documents I feel finding the right document to be far more important than the folder or place in which it is stored.
So to answer your question I would simply answer by saying it doesn’t really matter which structure you use, just that you should use some form of document management system (SharePoint, Documentum, Trim, etc). The benefits are simply too great to work without one :)
Related
Is there something similar to a standard library for modern ABAP (maybe even OO-Abap)? For example a curated list of objects that address some of the most common programming tasks like
high-level data structures (not just plain internal tables)
working with file paths and directories
working with files (reading, saving, ...)
working with different file types (text, csv, xml, ...)
regular expressions
working with the environment (client, application server)
...
My current workflow is to stumble upon a problem like getting the extension of a file from a filename (or something fairly similar and easy). Then I have three options:
Dig through a ton of (mostly old and lacking) posts on SDN until i maybe find a pointer to solve the problem
Hack away and create a one-off solution to the problem
Take my time and implement a good and well documented solution
Many times I feel a bit lost. A lot of the available information is old, bad or both. Is there a more structured approach to tackle the problem of finding a suitable abstraction in the ABAP-world?
To answer your first question no, unlike C, C#, Java, there is no need to include a library since all the functions are always available to you, so in that regards it might be simpler. What you are asking though is a great question, I am sure you probably see tons of queries in SDN for "Is there a Function module for?" etc.
There isn't an easy answer but In SAP ABAP I think the easiest way might be to find this is by looking at packages. Similar to a library by looking at a package for the type of function your looking for might get you there. For example if I am looking for handling files I might look for the control framework package and there I can see all the available functions/classes/methods/BAPIs etc. that are related to front end controls/file handling etc. and might be able to find what I am looking for. Note its not perfect as the way packages are used has changed from time to time so its actually better for finding functions related to for example purchasing or sales etc. but its one way that we use.
Like other languages in that we still need to know what library to link in to get the function you need, in ABAP you just have to find the related package. Hope it helps a little, I know its not perfect. Example package for front end controls
For working with the environment:
If you have access to SAP there is a transaction code called BAPI
Here you could find a hierarchical list of all the main objects in SAP (i.e. Material, Purchase Order, etc)
In this list you could find documentation, the function modules used for the object (i.e. créate/get detail/update etc)
And digging into the function modules could take a look to the structures, receiving parameters, etc
The other questions are a little bit complex, I am not aware of any comprehensive list but digging into SCN usually is easy to find a solution for the most common things like handling files, etc
In the particular case of regular expressions, SAP native language, ABAP, has keywords for handling them, but you also have a class in SAP called CL_JAVA_SCRIPT which you could use for doing thigs in "JavaScript way"
For example I used this class in the past to evaluate a simple formula provided in a string (i.e 3 + 2 * 5 )
This is an operation really complex to do in ABAP but easy to do in JS.
Hope it helps
SAP Reuse Library (SE83) is the most close thing to what you are looking for. It provides common development tasks grouped in hierarchy (UI controls, standard dialogs, confirmation prompts) and contains code snippets for each with commonly used classes/modules:
Though, it is incomplete and lacks many popular things.
Consider also DWDM, BIBS, LIBS transactions and other packages in this link.
I wonder if it is possible to configure MediaWiki (or other wiki tools) as a modular predefined wiki. For instance, on a regular wiki page one can freely edit sections, text, everything.
I am looking for a solution that predefines a number of sections (or modules) that can be added to each wiki page. Then users are free to edit inside those sections within their predefined formats.
Hope someone can help, thanks.
As for MediaWiki, there is at least one extension that can work that way: Semantic Forms, usually used together with Semantic MediaWiki (though that is not necessary). With SF, you will define one or more templates that receives the data entered in the form, and the form can be divided into sections.
A more lighweight solution might be using one of the many boiler plate extensions available.
Either way, with a wiki you can never force your users to follow a certain scheme. The whole philosophy, making wiki's unique among collaborative tools, is that the users, not you, create not only the content but also the structure for the content!
The former Semantic Forms is now called Page_Forms and it is not dependent on SMW https://www.mediawiki.org/wiki/Extension:Page_Forms and can also make use of the Cargo extension https://www.mediawiki.org/wiki/Extension:Cargo
I would disagree that wiki users cannot or should not be forced to follow a scheme for some types of information, though the default is that they do control the categories and namespaces and can create those at will as the data evolves. All this means though is that you manage such issues socially rather than with complex permissions structures, i.e. someone undoes your change and says "do it this way instead". So it's a different kind of forcing, but, still, someone has to make sure categories don't proliferate with bad names, capitalization, etc.
The typical use of forms data is when it must be used to satisfy some legal or professional requirement (say logging for what reason a change was made for Sarbanes-Oxley, or logging what precedents were consulted for logging legal time), or will be providing input strictly to some application (like maps). It would not be a good idea to rigorize literally every page of a wiki this way.
Developing functional specifications is never a pleasurable experience, but I kind of find a sick pleasure in planning a project well. I think I have some father issues.
Regardless of my own issues, I can find any number of articles on how to create a single functional spec in varying degrees of usefulness. There are templates and examples aplenty, and I've got a good library of my own. However I am finding it difficult to find anyone who discusses a manner in which to produce multiple functional specs with any efficiency.
Does anyone know of a source discussing how to manage the process of quickly generating disparate types of functional specs? Say a company that delivers web apps, perhaps using a rapid development tool like ColdFusion or PhoneGap or something where the experience lies within the use of the tool not the end result. So the functional specs can have a wonderful array of difference in them.
Can anyone point me towards a way of managing this process to ease the burden of building each of these from scratch?
EDIT - I really like OmniGraffle, however I'm not trying to maintain a look and feel or do anything visual (saving past screen shots might be useful if they can be indexed). Code Snippets seems closer to what I wanted. But in actuality I think I am looking for the method to archive/index past blocks of text.
So if I described a purchase order system a year ago and I am building something similar today, I want to find that functional spec from a year ago to have some example text to start from.
In my head this is liek some novel writing software where like code snippets a block of text (either a scene, chapter or blurb or whatever can be written and then moved aroudn int eh body of the whole. yWriter does this. However I need to find a way to index/search through these large chunks of text for relevance. I am hoping to learn more about that kind of system.
Fleshing out the ambiguity
If you are asking about templates that are primarily textual, then your best bet is probably just to have a 'stationary' file that you can open a copy, adding pieces that are copies of the template structure you've saved to the 'stationary', and then save out the draft spec.
If you are referring to diagrams and other visual schematic that follow a 'spec language' that is unique to your development framework, then I would suggest a tool like OmniGraffle, Visio, or LucidCharts, which have active communities that develop 'stencil libraries' (e.g. graffletopia)
I think you more mean #1, in which case you might look to examples like OmniOutliner templates which can contain sophisticated stylization of fonts and format, akin to 'type styles' in Word documents.
Code Snippets are one mechanism for solving this, but you will only get snippet libraries for programming IDEs, which generally will lack text style features. Code Snippet libraries are like text macros: short strips that expand into large blocks of text. You could create your own snippets for the different structures of project spec that related to each kind of framework.
Another solution is to leverage the file interoperability of tools like OmniGraffle and OmniOutliner (or other pairings). WhenOmniGraffle opens an Outliner file, it displays the list structure as a tree of objects/nodes. After adding more nodes, the OmniGraffle file can be re-opened in OmniOutliner and viewed as a list, with all the attached Outliner styles.
This is a nice multi-modal approach, but locks you into a toolset. Probably unavoidable until more people demand tooling to do this kind of thing.
This is an interview question which was asked to me (Not a homework question). I did give an answer but I wanted some professional opinion on whether the answer I gave was relevant or not. The proper question was:
Construct an object oriented design for the UNIX || Windows directory structure?
Thanks in advance!!
Since we're talking OO, I assume he wants you to concentrate on operations and structure.
A file and a directory would implement a common interface involving common operations but would also have their own operations.
A tree structure is involved, either the directories and files could be part of the tree or (as I'd probably do) the tree could be an external structure that references the files and directories.
I'd list the common operations in the interface (delete, getSize), the file-only operations (open, read, write, ...) in the file interface/object and the directory-only operations (changeDirectory, createChildDirectory, createFile) in the directory object.
The point, however, is that this is an open enough question to ensure that there is NO correct answer, rather it's a chance to evaluate how you "Think OO". There are millions of good solutions, the bad ones would be ones that didn't identify methods and members as part of the object model.
It's also a good chance to show off your level of design skills--seeing if you can intelligently communicate your model to others (UML is amazingly helpful in this--working without UML can be like working without a common language when it comes to heavy modeling)
The OO design will look basically the same as a dual linked tree with the ability to do cross-linking between nodes of two different types, hard and soft links.
There's also a bunch of complexity added in when you start to deal with permissions and meta-data, but those things are not specifically related to the directory structure.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 9 years ago.
Improve this question
I'm responsible of finding a good way to document the software project I'm working on.
What things are important to document? Should documentation of code and design mainly be in the code in the form of comments? Should we put text files or Word documents directly in the source control togetether with code? Should we use a wiki?
Factors to think about include how easy it is for the current team to create the documentation, and how easy it is for other developers to find, correct and extend the documentation later. My experience from many projects is that developers tend to not write documentation because the system for writing it is too complex or developer unfriendly, and that after a few years, new developers can hardly find the little documentation that was written.
I'm interested in what approaches you have used in similar projects. What worked well, what did not work well, and why?
Some key facts about the project:
The platform is C# and .NET.
We use Visual Studio and Team Foundation Server for source control and work item (task) management.
We use Scrum and test-driven development and are inspired by domain-driven design.
The software consists of a collection of web services and two GUI clients.
Other clients are going to integrate with the web services in the future. The integration will be done by other developers on other teams (so the web services form a kind of API).
SharePoint is heavily used throughout the development environment. Most projects have a SharePoint site, including ours.
On our project's SharePoint site we currently have a bunch of MS Office documents on things like requirements, design, presentations for stakeholders etc. Keeping everything up to date is hard.
We also have a SharePoint wiki for the development team only, where we document things in an unstructured manner as we go along. Examples include how our build scripts are organized, our testing policy, coding guidelines.
The software is an in-house application in a fairly big financial institution.
The software is developed by a team of six people over a period of ~1 year.
The developers are consultants hired in for this project only, and will not be available to help in the future (unless the client decides to pay for it).
The client has few guidlines for how this kind of project should be documented.
I think the most important things to document are the decisions. This goes for everything from requirements to architectural choices. What are the requirements of module X? How are these requirements represented in the architecture? Why did you choose architectural pattern A over B? What are the benefits? The same goes for source code: it is common knowledge that commenting the why is way better than the how.
How you document these decisions does not matter that much in my opinion, whether you use a Wiki or a Requirements document made in Word. More important is that these documents are always up-to-date and that it is easy for anyone to access them. This can be achieved by using a wiki, or placing the documents under source control, as you say. If only a few have access to them, they are more likely not to get updated, and not to be read when necessary.
We use a Wiki for our current project and it works very well. It is easy to access for anyone (developers, managers, and customers) and a history can track changes, so you know what has been changed and why. Furthermore, we try to document the code in a meaningful way and document the major design decisions. We try not to document too much, e.g. minor things, as it is always hard to keep those things up-to-date and it is not worth the effort, imho.
Worst for me than lack of documentation is excess of documentation.
Keep in mind that yes: it's really important to document your project, but also that the major part of your documentation is always at risk of never been read at all.
So, I think that a good starting point consist in thinking of your documentation more like something that you may use to introduce new developers to your project than an over detailed description of the inner workings of your software.
G'day,
Definitely use a wiki. I'd recommend TWiki as it's an excellent and extensive implementation of a wiki without being too complicated to install and manage.
Here's a couple of initial thoughts.
Categories:
Start off with an initial ontology of what you want to capture but
allow people to add new categories or sub-categories as required,
allow people to retitle (sub-)categories as required and maybe as agreed for this one so you don't get fragmentation for multiple names for basically the same thing.
let any initial (sub-)categories wither and die if they are left empty. Do this at the end of the project as some areas may only have entries towards the end of a project.
Tagging:
Start using a tag cloud. BTW here's an excellent plug-in available for TWiki to start classifying content early on in the project. Retrofitting tags is almost impossible to do. Starting tagging early also allows people to search for information that may be there already rather than having the same info located in multiple places.
HTH I'll come back and add more points as I think of them.
First and most important, have the comments written in such a way that NDoc can parse them. This is the best way to have the code itself documented, as the developers have to change their development practices very little, and you can generate pages that explain the code without having to look at the code.
Second, getting developers to write documentation is not easy, and getting them to do it might be an exercise in futility. This is where products like Fogbugz come into play. They will help manage the development with tickets, help track check ins, and when your done an iteration, generate release notes.
In conclusion, your best bet is to find the most effective solution that fits in with the devs existing process. If it impacts their development process very little, they will be more likely to adopt the system.