I am the Product Manager at a small startup, and I am trying to find a good set of templates to use for our design team. There are so many different variants out there, but I'd like something that I can standardize against. Obvious ones would be the IIBA and PMI templates, but they are more for Project Managers and pure BAs (very useful, but I need something more technical). I know back in my days at Nortel Networks, we used to do Design Specification Documents (DSDs), but I think it was just some cobbled together doc that someone made.
Can anyone point me in the right direction towards a set of "industry approved / accepted / recommended templates that I can use"? Something related to Architectural and Requirements that has boilerplate content that I just replace.
I was able to find the best answer. The best templates are to go to the source. PMI and IIBA:
https://stlouis.iiba.org/template-library
https://www.projectmanagement.com/Templates/index.cfm
Related
We're designing an app that will generate lots of different types of text output, eg email, html, sms, etc. The output will be generated using some kind of template, with data coming from a db. Our requirements include:
Basic logic / calculated fields within template. Eg "ifs" and "for" loops, plus some things like adding percentages for tax etc
Runtime editing. Our users need to be able to tweak the templates to their needs, such as change boilerplate text, add new logic, etc
Multi lingual. We need to choose the correct template for the current culture.
Culture sensitive. Eg dates and currencies will output according to current ui culture.
Flexibility. We need the templates to be able to handle multiple repeating groups, hierarchies, etc.
Cannot use commercial software as a solution (e.g. InfoPath). We need to be able to modify the source code at any time.
The app is c#.net. We are considering using T4, XML + XSLT or hosting the Razor engine. Given that the syntax cant be too overwhelming for non-techie users, we'd like to get your opinion on which you feel is the right templating engine for us. We're happy to consider ones notalready mentioned too.
Thanks.
I'm very hesitant to try and answer this question on a forum, because technology choices depend on far more factors than are conveyed in the question, including things such as attitude to risk, attitude to open source, previous good and bad experiences, politics and leadership on the project etc. The big advantage of XSLT over Razor is that it's a standard and has multiple implementations on multiple platforms (including at least three implementations on .NET!) so there's no lock-in; but that doesn't seem to be a factor in your statement of requirements. And the fact that you're using .NET suggests that supplier lock-in isn't something that worries you anyway.
One thing to bear in mind is that non-programmers often take to XSLT a lot more quickly than programmers do. Its rule-based declarative approach, and its XML syntax, sometimes make programmers uncomfortable (it's not like anything they have seen before) but end-users often take to it like ducks to water.
We've decided to go with Razor Hosting. The reason why I've posted this is an answer is that I thought it would help others if I include the following article link:
http://www.west-wind.com/weblog/posts/2010/Dec/27/Hosting-the-Razor-Engine-for-Templating-in-NonWeb-Applications
This excellent piece of work by Rick Strahl makes it really easy to host Razor.
My friends and I were thinking of starting our own wiki. Given how widespread they have become recently, we heard it isn't that hard. We want to keep the site as simple as possible - we have some experience with web design, but not a whole lot with system administration. What are some things that we should keep in mind going forward (such as, which wikifarms may be useful, or what caveats should we keep in mind)?
I'm guessing from your question that you mean for personal, instead of business, use.
As Bayard implies, the key to success is the social side. For the technical side you'll need to have a server (or someone prepared to host it) and good wiki software. The most obvious choice here is MediaWiki which is well developed (features), well tested, well known (through Wikipedia) and completely free. Furthermore, it can easily be extended with a variety of new features (extensions).
Take your time making the choice of software because it is hard to change later. WikiMatrix may help here (to compare software).
However, the social side is also important. What is your topic? Why is it necessary? Could you accomplish the same with Google Docs (if it is just for friends) or do you want a wider involvement?
If you want a wider involvement (e.g. allow the public to contribute), then decide whether you will permit anonymous edits.
Now the most important: moderation. This means (1) you need clear rules (like who can delete pages and what the process is) and (2) someone (or, better, a group) to enforce those rules (the moderators). You will need to create the right balance for you in terms of being strict with the rules (encourages quality) and being flexible (encourages participation).
You will also need someone to take a lead - to encourage, support and manage the moderators and processes. This person is often called a wiki champion. Here's a good link explaining more about this role.
Final tips: be clear what should go onto the wiki and what not, stay close to your users (customers) by encouraging feedback and keep it fun for everyone!
Later addition: check out these Stack Overflow questions and answers:
Getting developers to use a wiki
Getting started with a personal wiki and moinmoin
Does it make sense to set up a wiki at the workplace?
What’s the best open source wiki platform?
Another edition: make sure the moderators create and maintain great "how to" pages for the wiki. Often they are not intuitive (especially for people used to Word). You might want to start with a "What is a wiki?" page - and then, after a brief introduction, link to a Wikipedia page all about wikis.
MindTouch has a free, open source wiki (http://www.mindtouch.com/downloads) that sounds like it would be perfect for what you're trying to do. I've used it in the past and it's super easy to get up and running and very flexible. Watch one of their demos before you make any decisions though (http://www.mindtouch.com/support_and_services/demo_videos).
The most difficult part of implementing a successful wiki tends to be social, rather than technical. Wikipatterns is a good resource which describes the challenges you're likely to encounter.
I would like to know what do you use to sketch relations between different entities in C/C++. This can be a very broad issue, so I'll try to clarify a bit more my question and give an example.
I'm looking for something that is simple enough as a user, and let me sketch easily containers, pointers, etc... in an informal way.
The aim is to document some structs relations to pass them to junior developers. A look at the drawings is supposed to accelerate the understanding of the code.
My solutions at this moment are to use:
1) Paper & pencil.
2) Microsoft PowerPoint/Word Autoshapes.
3) Freeware Dia.
Other ones could be:
4) Microsoft Visio, but my company does not own licenses.
5) UML tools. I don't want to go this way. This is what I mean a more formal solution.
I know tools like Rational Rose are xxx, and I tried boUML and violet and they are fine in some parts, but I prefer the flexibility of options 1), 2) or 3).
Finally, let me write down a more concrete example:
Let's say I what to sketch a map that contains another map as the mapped value, and that one contains a struct as the mapped value, that holds a vector of pointers of a type and a pointer to other type. Also, there exist other structs that hold pointers to the objects pointed by the previous map, so there are objects pointed from different places.
This is just one example I have, but you can easily come with one from you experience.
What would you use to sketch this example or another similar you have dealt with?
Best regards,
Tomas.
Visio is great for quickly creating these types of illustrations / diagrams. I recommend at least trying to get your company to purchase a license.
If Visio is truly not an option for you, the next step may be to consider Open Source alternatives to Visio.
I have two things I use.
My whiteboard. Whiteboards are really tough to beat for diagramming something quickly.
UMLPad. It's small, so it doesn't have a ton of unrelated features to deal with, it is targeted to UML diagrams, and it is GPL.
For design issues, involving thoughts by a good many people, we've used "Post-It Design". The idea is simple:
Pick a whiteboard
Represent an entity as a Post-It (name + some comments)
Draw the relationships on the white board moving the post-its around as required
And when you're done ? Photo of the whole thing for perenity emailed to the persons involved :)
It may seem artisanal but it really remind me of the paper design approach to GUIs.
Have you tried Google Doc's Drawing? The link is one of the diagrams I've done with it.
I like yuml as a very easy way to create diagrams, that also keep that informal look. And no real drawing needed :)
I would use graphviz, but since you say "something that is simple enough as a user", dia is probably a better alternative.
I've used ArgoUML but you'll have to decide whether it's simple enough for what you have in mind.
For the sake of completeness: there's also StarUML, which is (windows) freeware and let's you create uml-diagrams pretty quickly.
Visual Paradigm UML the community edition is free and is good enough for sketching
Open Office Draw works for most of what you want to do too
You specify, that you are not just using U.M.L., most tools, these days are directed to specific U.M.L., you may want to look for a generic drawing tool.
At some projects, sometimes I use Open Office Draw, because, the company doesn't allow me to use another software (the company won't wan't to pay), its similar to Power Point or a reduced, simplified, version of Corel Draw:
http://www.openoffice.org/
In other cases, I have try both commercial and open source apps, but, doesn't like it.
At home, I use (paid software):
http://www.novagraph.com/
along with Open Office Draw.
These one, its also good (paid software):
http://www.smartdraw.com
Good Luck.
If you have an existing codebase you wish for a developer to understand (it sounds like you are trying to help junior devs come up to speed quicker) why not run your code through doxygen
With various output types and the ability to draw class hierarchies it really is a useful tool. The added benefit of something like the html output is that you dont have to cram everything into a finite amount of space since all relationships are hyperlinked. Users can just browse the source - at a type-level - without having to worry much about the details.
I would like to know if there are any templates for doing this in a clear and concise way to give the gist of the application and its inner workings and how it meets the business needs. I do not want to write a mythological story so looking for any new ways of doing this.
Mostly this is about documenting what you actually need from the system. You can't make a good choice if you don't know what you need.
Here is a doc-style approach.
This is a decision matrix approach outline. The formatting is rough, but this is a good approach. This one has better formatting, but is not about software (it doesn't really matter).
I'm not exactly sure if this is what you are asking for, but check out this paper. It's a sample implementation of the CMMI's "Decision and Analysis Resolution" process area. It basically documents a method for comparing alternatives, reaching a decision, and documenting that decision.
The SEI's site has the original definition of DAR (see page 181), as well as a pretty good presentation about it. You have to realize that their whole goal is to help companies define their processes, not to push a particular process. So the documents you find there tend to be pretty high level, discussing the goals that your process should achieve and the specific practices that should be covered.
Consult Eric Evans' "Domain Driven Design". At the end of the day, you're going to have to use your experience and judgment - and that of your team - to make the design decisions big and small, but Evans recommends formulating a one-page manifesto, written in business terms, to share with biz types that explains the value of your view of the domain to the business.
I'm creating a design document for a security subsystem, to be written in C++. I've created a class diagram and sequence diagrams for the major use cases. I've also specified the public attributes, associations and methods for each of the classes. But, I haven't drilled the method definitions down to the C++ level yet. Since I'm new to C++ , as is the other developer, I wonder if it might not make sense go ahead and specify to this level. Thoughts?
edit: Wow - completely against, unanimous. I was thinking about, for example, the whole business about specifying const vs. non-const, passing references, handling default constructor and assigns, and so forth. I do believe it's been quite helpful to spec this out to this level of detail so far. I definitely have gotten a clearer idea of how the system will work. Maybe if I just do a few methods, as an example, before diving into the code?
I wouldn't recommend going to this level, but then again you've already gone past where I would go in a design specification. My personal feeling is that putting a lot of effort into detailed design up-front is going to be wasted as you find out in developing code that your guesses as to how the code will work are wrong. I would stick with a high-level design and think about using TDD (test driven development) to guide the low-level design and implementation.
I would say it makes no sense at all, and that you have gone too far already. If you are new to C++ you are in no position to write a detailed design document for a C++ project. I would recommend you try to implement what you already have in C++, learn by the inevitable mistakes (like public attributes) and then go back and revise it.
Since you're new, it probably makes sense not to drill down.
Reason: You're still figuring out the language and how things are best structured. That means you'll make mistakes initially and you'll want to correct them without constantly updating the documentation.
It really depends on who the design document is targeted at. If it's for a boss who is non-technical, then you are good with what you have.
If it's for yourself, then you are using the tool to help you, so you decide. I create method level design docs when I am creating a project, but it's at a high level so I can figure out what the features of the various classes should be. I've found that across languages, the primary functionalities of a class have little to do with the programming language we are working in. Some of the internal details and functions required certainly vary due to the chosen language, but those are implementation details that I don't bother with during the design phase.
It certainly helps me to know that for instance an authorization class might have an authenticate function that takes a User object as a parameter. I don't really care during design that I might need an internal string md5 function wrapper to accomplish some specific goal. I find out about that while coding.
The goal of initial design is to get organized so you can make progress with clarity and forethought rather than tearing out and reimplementing the same function 4 times because you forgot some scenario due to not planning.
EDIT: I work in PHP a lot, and I actually use PhpDoc to do some of the design docs, by simply writing the method signature with no implementation, then putting a detailed description of what the method should do in the method header comments. This helps anyone that is using my class in the future, because the design IS the documentation. I can also change the documentation if I do need to make some alterations while coding.
I work in php4 a lot, so I don't get to use interfaces. In php5, I create the interface, then implement it elsewhere.
The best way to specify how the code should actually fit together is in code. The design document is for other things that are not easily expressed in code. You should use it for describing the actual need the program fills, How it interacts with users, what the constraints are in terms of hardware and operating systems. Certainly describe the overall architecture of your application in a design document, but, for instance, the API should actually be described in the code that exposes the API.
You have already gone far enough with the documentation part. As you still a beginner in C++, when you would understand the language, you might want to change the structure of your program. Then you would have to do changes in the documentation. I would suggest that you have already gone too far with the documentation. No need to drill more into it
Like everyone else says, you've gone way past where you need to go with the design. Do you have a good set of requirements to the simple true/false statement level that you derived that design from? You can design all day long, but if you don't have requirements that simply say WHAT you're going to do, it doesn't matter how good your design is.