Closed. This question needs to be more focused. It is not currently accepting answers.
Want to improve this question? Update the question so it focuses on one problem only by editing this post.
Closed 6 years ago.
Improve this question
I inherited an old app, written in C#/.NET 2.0. (un)Luckily there was no documentation - not even comments. So as I'm adding enhancements to the application based on new requirements I'm also building a mental model of what the app does and how it does it - architecture in other words.
I was wondering what tools exist out there to "deconstruct" the app and go from raw code to something higher level? The app's not really heavy in OO - in fact one of the objects used is called a "function". It's mostly just a bunch of methods - a lot methods that seem to jump out of nowhere.
I want to translate the raw code to some sort of requirements doc stating what the app does and how it executes. What's the best way to do it? Are there any apps out there that can help me? Maybe templates of what I should/should not include? Maybe books/sites that you recommend? The goal is to provide documentation for me and for future developers maintaining the app.
Personally, I would start with Robert C Martin's Agile book, and Eric Evan's book on Domain Driven Design. Those are theory books, but Uncle Bob's book specifically talks about revamping code to be manageable, just like your situation.
It's pretty essential to layer your software so you can start to remove dependencies, which will make everything very simple and easy to maintain.
I am a database guy, so I started with a good ORM like Entity Framework or Fluent NHibernate. I prefer websites, so I went with ASP.NET's MVC 2, then started writing all the parts of those books, namely a data Repository, Services to pull data and Control to push it. MVC is a very nice separation of data concerns and "View" concerns which are your screens. Before long, you would have very clean and easily maintained software.
If you are using VS 2010, you can see a menu with the name: Architecture. Using this tool, you can create a dependency graph of your application, you can use it as described in the following:
Link
Related
Closed. This question is off-topic. It is not currently accepting answers.
Want to improve this question? Update the question so it's on-topic for Stack Overflow.
Closed 9 years ago.
Improve this question
Gathering requirements is an essential stage creating software or web applications.
I have searched the web extensively without finding any directions on how to elicit requirements for personal projects. All information i found - including books i read - is focussing on different stakeholders.
So i´m wondering, what would be the best way to 'gather' the requirements for personal projects?
I can't imagine i'm the only one with this question. I have plenty of ideas for webapplications. Since i am the only stakeholder at this time - no users are identified yet, i need to develop a couple of applications for personal use - i find it hard to interview my self to elicit those requirements.
As English is not my native language, apologies for possible textual errors.
You can have a document with all the information you have in your head of the project in a bullet list format called "Project Memoir". Just list all the information & business rules you need to put in the project. You can after that start developing a kind of informal Software
requirements document (as it's for a personal project) containing some essential information for you in the development phase, like a feature list with their description, use cases & scenarios that will help you in testing in later phase, mock up screens for defining the UI look & elements, data elements lists for defining screen contents. Just keep it simple & easy as it's for only your personal use.
Hope that would help :)
The questions are supposed to be a trigger of a thought process.
What makes it any different in case you are the developer next to the stakeholder? Your thoughts are those of a stakeholder and you will have to try to identify your own requirements by this process.
Identifying your own requirements with a structured approach will help you identifying requirements that you would otherwise have encountered during development.
If the sole purpose is not only personal, I doubt whether it is a good idea to start developing. Then you will need to find prospects to interview. Investigate the possible markets.
Closed. This question needs to be more focused. It is not currently accepting answers.
Want to improve this question? Update the question so it focuses on one problem only by editing this post.
Closed 7 years ago.
Improve this question
Can anyone give advice, or point to any guides, on how to manage a community of open source software developers in writing api documentation?
A typical, unmanaged, starting point for most projects is to have a project wiki where anyone can freely create pages, add content to existing pages, edit existing content etc. The problem is that, despite people's best intentions, the wiki can easily end up being a disorganised, poorly written, incomplete, written in disparate voices etc etc.
So, what to do to improve the quality of the documentation?
I suspect a key ingredient is clear editorial/style guidelines, something similar to http://en.wikipedia.org/wiki/Wikipedia:Encyclopedic_style#Information_style_and_tone. Can anyone point to an example of such a guide tailored specifically to software apis?
Are there any other practices that people have found useful? E.g. form a core team of editors and accept that most documentation that gets added by the community will most likely need to be 'strongly edited'?
The short answer, that the solution is social/human and not technical. The way to get good documentation for any project is to have someone with time, in charge of doing high level organization for the documentation, and then being involved in the development and user communities to ensure that the documentation remains up to date and continues to address the problems and confusions that users typically have.
Community projects have accepted that you need point people (i.e. "managers," for aspects of the project like "translation," and "release," and for various components. The same thing needs to happen for documentation.
As for tools, Sphinx is really great though it's not "wiki like," exactly you can use whatever version control system your project is comfortable with to store documentation and configure your web server to rebuild the documentation following commits/updates/pushes. Which has always worked just fine for any project I've worked on/with.
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
We want to implement a model or guideline for our OO designs,. We like Domain-Driven Design. Our specific question is: do you think DDD is still valid right now beyond the pattern design? If so, do other approaches or variants exist that we should evaluate ?
Fundamentally we develop enterprise web and desktop applications using Visual studio (c#).
Thanks in advance
In my opinion, DDD is as pertinent today as ever. The idea that one should strive for an Ubiquitous Language, such that the domain in code is not divorced from the domain as described by the domain experts, will probably remain a good idea for a long time, and it is easier today to focus on the domain first and consider persistence as a "secondary" problem than it used to be. It is also still true that DDD requires an important design effort, and its value is going to be proportional to how complex the domain is.
I have not written any application using the methodology, but I have been reading a lot on Event Sourcing and CQRS lately, and they both seems like a very interesting approach which should fit well with DDD (and are usually advocated by people who are DDD proponents).
I can't find it right now, but there is a video interviews of Eric Evans floating around somewhere on the web,You may be interested in watching this video of Eric Evans, which is a form of retrospective on the methodology a few years after writing the book, and what he would have done differently now.
I think DDD is quite alive (or quite as dead) as before. My opinion is that the "domain" is a hot topic today because of DSLs (Domain-Specific Languages) and MDE (Model-Driven Engineering).
You may want to learn more about a similar "domain-driven" aproach, called DSM - Domain-Specific modeling. In DSM, you can work through patterns but you also define code generators that translate your domain-specific design into working code.
Check the DSM Forum or Wikipedia for more information about DSM.
The two most notable tools right now in this area are MetaEdit+ from MetaCase and AtomWeaver from Isomeris.
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 5 years ago.
Improve this question
I work for a insurance company. We have our own development department made-up of almost 150 people plus some providers (outsourcing and custom made apps pretty much). In our company my team have made what we call non-functional logic libraries. That is, software libraries to handle things that are horizontal to all the development teams in our department, e.g. Security, Webservices, Logging, Messaging and so on. Most or these tools are either made from scratch or adaptation of a de-facto standard. For example our logger is an appender based on Log4J that also saves the logging messages into a DB. We also define what libraries to use in the application, for example which framework for webservices to use. We use pretty much JavaEE and Oracle AS in all our organization (with some Websphere Application servers).
Much of these projects have their architecture documented (use cases, UML diagrams, etc) and generally the generated documentation are available.
Now what we have seen is that for users sometimes is difficult to use the the libraries we provide and the are constantly asking question or they simply don't use them.
So we are planning to generate a more friendly documentation for them, so my question is:
What are the best practices or the checklist that software documentation should have?
Something comes to my mind:
API Reference guide
Quick start Tutorial
API Generated Documentation.
Must be searchable
Web Access
What else should it have? Also, based in your experience what is the best way to maintain (keep it up-to-date) and publish this type of documentation?
Keep your documentation in version control too.
Make sure on every page it has a version number so you know where your user has been reading from.
Get a CI server going and push documentation to a LIVE documentation site upon updates.
Do documentation reviews like you would code reviews.
Dog-food it :)
Kindness,
Dan
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 5 years ago.
Improve this question
I am developing an application that can be extended using "plug-ins". The plug-ins will be pretty basic, allowing developers to add new "actions" to my application.
What documentation/information do I need to provide so that developers can do what they need to?
I was thinking a short example and a general overview of how the application/plug-ins work?
You need to foster a sense of community. Things like:
sample code for more than one real plugin;
a getting started guide for plugin writers;
details on how to deploy a plugin and on how they are discovered by your application;
a wiki so that plugin writers can collaborate, and
an easy way for plugin authors to contribute their plugin
might help.
You also have to decide how detailed your API is going to be. IF you are offering a rich API, make sure to document it well, and to explicitly highlight directives (explicit "do" or "don't do" instructions).
Most users will not bother to read the documentation and figure out things from the name, or skim your docs. So it is best if you can avoid "surprising them", and if not, at least offer them a chance to find the problems.
Finally, err on the side of caution with checking correct use and send exceptions rather than counting on users meeting your instructions.
Also, think very well in advance on whether you truly expect anyone to use your plug-ins because the core product becomes a "hit".
It is very common to err on the side of optimism, and think that when you are writing a plug-in infrastructure that somebody will actually use it.
However, nobody is likely to write plugins before the core out-of-the-box offering is successful and popular. You may be better off publishing and distributing your own plugins before worrying about extensions by others.